<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	
	<head>
		<meta http-equiv="Content-Language" content="en-gb" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="description" content="Text, fonts and text styles" />
		<title>PDF Graphics .NET documentation - Text, fonts and text styles</title>
		<link rel="stylesheet" href="../style/Help.css" type="text/css" />
		<link rel="stylesheet" href="style/Text_fonts_styles.css" type="text/css" />
	
	</head>
	
	<body>
		<div class="navigator">
			<span>
				<strong>PDF Graphics .NET</strong> :: <a href="..\Index.html">Help</a> :: <a href="..\Painting_graphics.html">Painting graphics</a> :: Text, fonts and text styles
			</span>
		</div>
		
		<h1>Text, fonts and text styles</h1>
		
		<p>
			This section covers the following topics:
			<ul>
				<li><a href="#Fonts">Fonts</a></li>
				<li><a href="#WritingText">Writing text</a></li>
				<li><a href="#Formatting">Text formatting</a></li>
				<li><a href="#StyledText">Fully-styled text</a></li>
				<li><a href="#FontManagement">Font management</a></li>
			</ul>
		</p>
			
		<h2><a name="Fonts"></a>Fonts</h2>
		
		<p>
			All text drawing operations of PDF Graphics .NET require fonts. A font contains all the information needed to
			render letters, markup and other tokens for a given type, such as Times New Roman. PDF Graphics .NET uses the
			font information stored in the system; if you have installed a font, it will be available to draw text onto a PDF
			page.
		</p>
		
		<p>
			To write text onto a page, you need to create an instance of the <span class="code">Font</span> class.
			Its constructor accepts the name of a type, which must be that type's full name. That means that in order
			to write bold-face text in Times New Roman, you need a <span class="code">Font</span> instance for
			<span class="code">&quot;Times New Roman Bold&quot;</span>. If the font does not exist in the system,
			an exception is raised. The following are all examples of font instances:
		</p>
			
			<div class="sampleCode">Font font1 = new Font("Times New Roman");
Font font2 = new Font("Arial Narrow Bold Italic");
Font font3 = new Font("Bookman Antiqua");</div>
				
		<p>
			A <span class="code">Font</span> instance is not tied to the current page, or even a <span class="code">Graphics</span> instance.
			You can use the same instance on multiple pages, and across Graphics instances.
			</p>

		<h2><a name="WritingText"></a>Writing text</h2>

		<p>
			The <span class="code">Graphics</span> class provides a number of methods for drawing text. In its simplest form,
			the overloaded <span class="code">DrawString()</span> method accepts a brush, font and size, and the (x,y) coordinates to start
			drawing at.
		</p>
		
		<div class="sampleCode">Font myFont = new Font("Times New Roman");

g.DrawString(Rgb.BlackBrush, "The quick brown fox...", myFont, 12f, 20, 20);</div>  
						
		<p>
			This draws the text <span class="code">&quot;The quick brown fox...&quot;</span>, with the top-left hand corner
			at the point (20, 20). The text is drawn at 12 points size. The <span class="code">size</span> parameter is always
			expressed in points, no matter what the current page unit is.
		</p>
		
		<p>
			In this simple form, text is drawn on a single line and does not wrap. If the text is too long to fit on the page, it is clipped,
			as can be seen in the following example:
		</p>
		
		<div class="sampleCode">Font myFont = new Font("Times New Roman");

g.DrawString(Rgb.BlackBrush, "The quick brown fox...", myFont, 12f, 450, 20);</div>  

		<p><img src="../images/TextClipped.jpg" title="The text 'The quick brown fox...' is clipped."/></p>
		
		<h3>Text in a bounding box</h3>
		
		<p>
			Another overload of <span class="code">DrawString()</span> accepts a <span class="code">Rectangle</span> instance to be
			used as the bounding box of the text. The text will now wrap and continue onto subsequent lines, provided there is enough
			space in the bounding box to fit all the lines. Lines that do not fit are not drawn at all. The code below illustrates this:
		</p>
		
				<div class="sampleCode">Rectangle bbox = new Rectangle(20, 50, 100, 60);
g.DrawRectangle(redPen, bbox);

g.DrawString(  blackBrush, "The quick brown fox jumps over the lazy dog.",
               font, 12, bbox); 

bbox = new Rectangle(150, 50, 100, 30); // Too small to fit the text...
g.DrawRectangle(redPen, bbox);

g.DrawString(  blackBrush, "The quick brown fox jumps over the lazy dog.",
               font, 12, bbox);</div> 

		<p><img src="../images/Text_Inside_Bounding_Box.jpg" title="Text inside a bounding box."/></p>

		<p><strong>Note:</strong> If the bounding box does not fit onto the page, the text will of course still be clipped.</p>
		
		<h2><a name="Formatting"></a>Text formatting</h2>
		
		<p>
			So far, we have drawn text without specifying formatting details. PDF Graphics .NET provides a number of formatting
			options through the <span class="code">StringFormat</span> class and an overload of <span class="code">DrawString()</span>
			that accepts a <span class="code">StringFormat</span> instance. These options control the alignment of text, as well as
			various types of spacing. The formatting options are only available when drawing text inside a bounding box.
		</p>
		
		<h3>Character spacing</h3>
		
		<p>
			Character spacing is controlled through the <span class="code">CharacterSpacing</span> property of the
			<span class="code">StringFormat</span> class. By default, character spacing is set to 0. Positive and negative
			values are allowed. Character spacing is measured in points, regardless of the page unit.
		</p>
		
		<table>
			<thead>
				<th colspan="2">Character spacing</td>
			</thead>
			<tr>
				<td class="centered"><img src="../images/DefaultStringFormat.jpg" title="Text drawn with default character spacing" /></td>
				<td class="centered"><img src="../images/CharacterSpacing.jpg" title="Text drawn with character spacing set to 2 points." /></td>
			</tr>
			<tr>
				<td class="centered">Default character spacing</td>
				<td class="centered">2 points spacing</td>
			</tr>
		</table>

		<h3>Word spacing</h3>

		<p>
			Word spacing is controlled through the <span class="code">WordSpacing</span> property of the
			<span class="code">StringFormat</span> class. By default, word spacing is set to 0. Positive and negative
			values are allowed. Word spacing is measured in points, regardless of the page unit.
		</p>
		
		<table>
			<thead>
				<th colspan="2">Word spacing</td>
			</thead>
			<tr>
				<td class="centered"><img src="../images/DefaultStringFormat.jpg" title="Text drawn with default word spacing" /></td>
				<td class="centered"><img src="../images/WordSpacing.jpg" title="Text drawn with word spacing set to 4 points." /></td>
			</tr>
			<tr>
				<td class="centered">Default word spacing</td>
				<td class="centered">4 points spacing</td>
			</tr>
		</table>
				
		<h3>Line spacing</h3>

		<p>
			Line spacing is controlled through the <span class="code">LineSpacing</span> property of the
			<span class="code">StringFormat</span> class. By default, line spacing is set to 0. Positive and negative
			values are allowed. Line spacing is measured in points, regardless of the page unit.
		</p>
		
		<table>
			<thead>
				<th colspan="2">Line spacing</td>
			</thead>
			<tr>
				<td class="centered"><img src="../images/DefaultStringFormat.jpg" title="Text drawn with default line spacing" /></td>
				<td class="centered"><img src="../images/LineSpacing.jpg" title="Text drawn with line spacing set to 3 points." /></td>
			</tr>
			<tr>
				<td class="centered">Default line spacing</td>
				<td class="centered">3 points spacing</td>
			</tr>
		</table>
			
		<h3>Text ratio</h3>

		<p>
			Text ratio is controlled through the <span class="code">TextRatio</span> property of the
			<span class="code">StringFormat</span> class. By default, text ratio is set to 1. A value of 0.5
			narrows text to 50%. A value of 2 doubles the width of text. Negative values are not allowed.
		</p>
		
		<table>
			<thead>
				<th colspan="2">Text ratio</td>
			</thead>
			<tr>
				<td class="centered"><img src="../images/DefaultStringFormat.jpg" title="Text drawn with default ratio" /></td>
				<td class="centered"><img src="../images/TextRatio.jpg" title="Text drawn with text ratio 0.7." /></td>
			</tr>
			<tr>
				<td class="centered">Default ratio</td>
				<td class="centered">0.7 ratio</td>
			</tr>
		</table>
									
		<h3>Vertical alignment</h3>

		<p>
			Vertical alignment is controlled through the <span class="code">VerticalAlignment</span> property of the
			<span class="code">StringFormat</span> class. Text can be aligned to the top of the bounding box (the top of the first line will
			be equal to the top of the bounding box) or to the bottom (the bottom of the last line will be aligned to the bottom of the
			bounding box), or centered within the bounding box. By default, text is aligned to the top of the bounding box.
		</p>
		
		<table>
			<thead>
				<th colspan="3">Vertical alignment</td>
			</thead>
			<tr>
				<td class="centered"><img src="../images/DefaultStringFormat.jpg" title="The text is aligned to the top of the bounding box." /></td>
				<td class="centered"><img src="../images/VerticalAlignmentCenter.jpg" title="The text is vertically centered." /></td>
				<td class="centered"><img src="../images/VerticalAlignmentBottom.jpg" title="The text is aligned to the bottom of the bounding box." /></td>
			</tr>
			<tr>
				<td class="centered"><span class="code">VerticalAlignment.Top</span></td>
				<td class="centered"><span class="code">VerticalAlignment.Center</span></td>
				<td class="centered"><span class="code">VerticalAlignment.Bottom</span></td>
			</tr>
		</table>

		<h3>Horizontal alignment</h3>

		<p>
			Horizontal alignment is controlled through the <span class="code">HorizontalAlignment</span> property of the
			<span class="code">StringFormat</span> class. Text can be aligned to the left or right side of the bounding box,
			or centered within the box, or fully justified. Fully justified text spans the width of the bounding box. This
			implies that on each line, word spacing is adjusted to make the text fill the entire width. This overrules the
			word spacing currently in effect. By default, text is left-aligned.
		</p>
		
		<table>
			<thead>
				<th colspan="4">Horizontal alignment</td>
			</thead>
			<tr>
				<td class="centered"><img src="../images/DefaultStringFormat.jpg" title="The text is aligned to the left." /></td>
				<td class="centered"><img src="../images/HorizontalAlignmentCenter.jpg" title="The text is horizontally centered." /></td>
				<td class="centered"><img src="../images/HorizontalAlignmentRight.jpg" title="The text is aligned to the right of the bounding box." /></td>
				<td class="centered"><img src="../images/HorizontalAlignmentFullyJustified.jpg" title="The text is fully justified." /></td>
			</tr>
			<tr>
				<td class="centered"><span class="code">HorizontalAlignment.Left</span></td>
				<td class="centered"><span class="code">HorizontalAlignment.Center</span></td>
				<td class="centered"><span class="code">HorizontalAlignment.Right</span></td>
				<td class="centered"><span class="code">HorizontalAlignment.FullyJustified</span></td>
			</tr>
		</table>
											
		<h2><a name="StyledText"></a>Fully-styled text</h2>
		
		<p>
			In all the examples above, text was written in a single font. While this is sufficient in most cases, sometimes a piece of
			text requires multiple font styles (bold, or italic) or even different font types. PDF Graphics .NET supports
			this in the form of the <span class="code">DrawStyledText()</span> method in conjunction with the
			<span class="code">StyledText</span> class.
		</p>
		
		<p>
			The <span class="code">StyledText</span> class is composed of one or more text elements, each with its own style.
			The elements are represented by instances of the <span class="code">InlineText</span> class, which encapsulates a
			brush, font and font size, together with the text to draw in that style. Text elements are added to a
			<span class="code">StyledText</span> instance by calling its <span class="code">Append()</span> method with
			an <span class="code">InlineText</span> argument. Alternatively, specify the style properties directly using
			an overload of <span class="code">Append()</span>.
		</p>
			
		<p>
			To draw styled text, create a new instance of <span class="code">StyledText</span> and add text sections to it using one
			of its <span class="code">Append()</span> method overloads. Alternatively, you can use one of the overloaded
			constructors of <span class="code">StyledText</span> and specify text sections directly. Finally, call
			<span class="code">DrawStyledText()</span> on the <span class="code">Graphics</span> object to place the styled text.
			All of the example below have the same result:
		</p>

		<div class="sampleCode">StyledText text = new StyledText();
			
text.Append(new InlineText("This text includes ", Rgb.BlackBrush, font, 12));
text.Append(new InlineText("emphasised", Rgb.BlackBrush, boldFont, 12));
text.Append(new InlineText(" parts", Rgb.BlackBrush, font, 12));

g.DrawStyledText(text, bounds, format);</div>

		<p></p>
			
		<div class="sampleCode">StyledText text = new StyledText();

text.Append("This text includes ", Rgb.BlackBrush, font, 12);
text.Append("emphasised", Rgb.BlackBrush, boldFont, 12);
text.Append(" parts", Rgb.BlackBrush, font, 12);

g.DrawStyledText(text, bounds, format);</div>

		<p></p>
		
		<div class="sampleCode">StyledText text = new StyledText(
    "This text includes ", Rgb.BlackBrush, font, 12);
    
text.Append("emphasised", Rgb.BlackBrush, boldFont, 12);
text.Append(" parts", Rgb.BlackBrush, font, 12);

g.DrawStyledText(text, bounds, format);</div>

		<p>The <span class="code">Append()</span> methods return a reference to the <span class="code">StyledText</span> instance,
		so you can daisy-chain the calls. The following example produces the same output as the ones above:</p>

		<div class="sampleCode">g.DrawStyledText(
    new StyledText()
        .Append("This text includes ", Rgb.BlackBrush, font, 12)
        .Append("emphasised", Rgb.BlackBrush, boldFont, 12)
        .Append(" parts", Rgb.BlackBrush, font, 12),
    bounds, format);</div>
			
		<p><img src="../images/StyledText.jpg" title="Styled text" /></p>
		
		<p>
			<strong>Note:</strong> In the examples above, the first and last text elements include a space at their end and start, respectively.
			Although the InlineText elements seem to work like words in a sentence, the spaces are essential. Without them, the text elements
			would be joined together, as in the following example:
		</p>
		
		<div class="sampleCode">g.DrawStyledText(
    new StyledText()
        .Append("Em", Rgb.BlackBrush, italic, 12)
        .Append("phasis", Rgb.BlackBrush, font, 12),
    bounds, format);</div>

		<p><img src="../images/JoinedElements.jpg" title="Styled text with joined elements" /></p>
			
		<h3>Line height</h3>
		
		<p>
			The height of a line of text is determined by the size of the text. When text is composed of multiple fonts, line height is
			based on the tallest font. This takes into account the sizes of fonts used in <span class="code">InlineText</span> elements
			as well as some font metrics, such as the 'descent' figure. In the example below, one of the lines is moved down to
			accommodate the larger font used in some of the text.
		</p>

		<div class="sampleCode">g.DrawStyledText(
    new StyledText()
        .Append(
            "Some of the text in this example uses a ", 
            Rgb.BlackBrush, font, 12)
        .Append("larger", Rgb.BlackBrush, font, 16)
        .Append(
            " font. As a result, one of the lines ", 
            Rgb.BlackBrush, font, 12)
        .Append("is moved down.", Rgb.BlackBrush, font, 12),
    bounds, format);</div>

		<p><img src="../images/MultipleFontSizes.jpg" title="Styled text with multiple font sizes." /></p>
		
		<h2><a name="FontManagement"></a>Font management</h2>
		
		<p>
			Because PDF was designed to allow portable documents, the specification provides document creators with a degree of control
			over the handling of fonts. A PDF document may contain copies of the fonts used on its pages, or it can rely on
			system-installed versions. For a handful of standard fonts, such as Times New Roman, it is safe to assume a font exists on
			target systems. For other fonts, however, embedding the font inside the document guarantees that the document retains
			fidelity.
		</p>
		
		<p>
			PDF Graphics .NET library embeds fonts by default, except for the 'stock' fonts guaranteed by Adobe to be rendered
			correctly. However, if for some reason you are using a font that cannot be embedded (it may be too large to include
			in your document, or licence restrictions prevent you from spreading it), the <span class="code">Font</span>
			class provides an option to disable the embedding. The following code creates a font that will not be embedded
			in the PDF document:
		</p>

		<div class="sampleCode">Font font = new Font("DIN Medium", false);</div>
		
		<p>
			This means that the PDF document will not render accurately; that is, the PDF reader (such as Adobe Acrobat
			Reader) will render the text in a standard font. However, PDF Graphics .NET will provide the PDF document
			with character spacing information so that the text is rendered in the same size as the original, and no
			text will be clipped or appear out of place.
		</p>
			
		<h3><strong>Navigation options:</strong></h3>
		<p><a href="Shapes.html">&lt; Shapes</a> | <a href="Images_stencils.html">Images and stencils &gt;</a>
		
	</body>
	
</html>